Wake sleeping backends with an isolated browser document request - #124
Merged
Conversation
A user navigation successfully woke the backend after background health requests had timed out. Request one isolated health document during warmup, and retain the existing JSON readiness and retry checks. Restrict the document to a configured HTTPS Render origin and remove it on success, timeout or cancellation. Tests and production build pass; a real cold-start check remains required.
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The change is tightly scoped, has explicit safety/URL guardrails and deterministic cleanup, and is covered by targeted tests for wake behavior, timeout, cancellation, and restrictions.
Pull request overview
Adds a browser-only, fully sandboxed hidden document request (iframe) to help wake a sleeping Render backend during warmup without navigating away from the current tab, while still requiring the existing JSON health probes to determine readiness.
Changes:
- Introduce
mountBackendWakeDocument()to mount and reliably remove a hidden sandboxed iframe targeting${backend.origin}/healthwhen the configured base URL is a strict HTTPS*.onrender.comorigin. - Wire the mount/remove lifecycle into
waitForBackendReady()so cleanup happens on success, timeout, or cancellation. - Expand warmup tests to cover document-dependent wake behavior, timeout/cancellation cleanup, and URL restriction cases (with a VM-injected browser/document).
File summaries
| File | Description |
|---|---|
| tools/tests/backend_warmup_rate_limit.test.mjs | Extends the warmup harness to inject URL/browser globals and adds focused tests for the new iframe-based wake behavior and URL guardrails. |
| frontend/lib/backendRequest.ts | Adds a guarded hidden sandboxed iframe “wake” request during backend warmup, with guaranteed cleanup in finally. |
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Login succeeds while the backend is running, then stalls before Xaman after the backend becomes idle. On 2026-09-06 the backend stopped at 14:50:26; background warmup requests did not restart it. A user subsequently opened its public health URL in the same browser, saw Render's loading page, and received the expected health JSON.
This change adds one hidden, fully sandboxed document request to the configured HTTPS Render health URL during warmup. It reproduces a browser document request without leaving the original login tab. Existing health probes must still confirm the expected JSON; the document's load event does not establish readiness. Retry-After handling and the 180-second overall deadline remain in place. The document is removed on success, cancellation or timeout.
The URL guard excludes credentials, arbitrary origins, non-HTTPS URLs, ports, paths, queries and fragments. The frame has no sandbox permissions and sends no referrer. Backend framing protections remain intact.
Validation: 36 focused warmup, login and logout tests pass; Next.js production build, lint and type checks pass. The new tests cover simulated document-dependent startup, timeout, cancellation, and URL restrictions. Only two files change.
Evidence limit: a top-level navigation has been observed live; an embedded document request still needs a real cold-start acceptance check. This PR does not claim the production incident is resolved. Existing frontend release ffa4178 is the rollback reference.